Policies

Define authorization rules to control access to your application's resources.

Overview

Policies provide fine-grained access control using Cerbos-style policy definitions. Create resource policies, principal policies, and derived roles to determine who can do what in your application.

---

Concepts

Resource Policy

Defines access rules for a specific resource type (e.g., documents, orders). Specifies which actions are allowed for which roles under what conditions.

Principal Policy

Overrides resource policies for specific users or groups. Useful for granting or denying access to particular individuals.

Derived Roles

Dynamic roles computed from user attributes at runtime. For example, "document_owner" when the user's ID matches the document's owner_id.

---

View Policies

1. Navigate to your App in the Dashboard.
2. Click Policies in the sidebar.
3. View policies in two modes:
   • List View: All policies in a searchable list
   • Graph View: Visual representation of policy relationships

Policy Types

Policies are color-coded by type:

• Resource Policies: Blue
• Principal Policies: Orange
• Derived Roles: Green

---

Policy Editor

The policy editor provides multiple views for working with policies:

Form View

Visual form editor for policy structure:

1. Click the Form tab.
2. Edit rules using dropdowns and inputs.
3. Add conditions using the condition builder.

Code View

YAML/JSON code editor:

1. Click the Code tab.
2. Edit the policy definition directly.
3. Changes sync with the Form view.

Flow View

Visual flowchart of policy rules:

1. Click the Flow tab.
2. See the decision flow for access checks.
3. Understand how rules are evaluated.

Test View

Built-in policy testing:

1. Click the Test tab.
2. Create test scenarios.
3. See pass/fail results for each scenario.

---

Create a Resource Policy

1. Navigate to Policies in your app.
2. Click Create Policy.
3. Select Resource Policy.
4. Configure the policy:
   • Resource: The resource type this policy applies to
   • Version: Policy version (e.g., "default")
5. Add rules:
   • Actions: What can be done (read, write, delete)
   • Roles: Who can do it (admin, user, guest)
   • Conditions: When the rule applies (optional)
6. Click Create.

Example Resource Policy

apiVersion: api.cerbos.dev/v1
resourcePolicy:
  resource: document
  version: default
  rules:
    - actions:
        - read
        - write
      effect: EFFECT_ALLOW
      roles:
        - admin
    - actions:
        - read
      effect: EFFECT_ALLOW
      roles:
        - user
      condition:
        match:
          expr: request.resource.attr.is_published == true

---

Create a Principal Policy

1. Navigate to Policies in your app.
2. Click Create Policy.
3. Select Principal Policy.
4. Configure:
   • Principal: User ID or identifier
   • Version: Policy version
5. Add overrides for specific resources.
6. Click Create.

---

Create Derived Roles

1. Navigate to Policies in your app.
2. Click Create Policy.
3. Select Derived Roles.
4. Configure:
   • Name: Role set name
   • Definitions: Role definitions with conditions
5. Click Create.

Example Derived Roles

apiVersion: api.cerbos.dev/v1
derivedRoles:
  name: document_roles
  definitions:
    - name: owner
      parentRoles:
        - user
      condition:
        match:
          expr: request.resource.attr.owner_id == request.principal.id

---

Test Policies

1. Navigate to a policy.
2. Click the Test tab.
3. Create test scenarios:
   • Principal: User attributes
   • Resource: Resource attributes
   • Action: Action to test
4. Click Run Tests.
5. View results showing allowed/denied.

---

Graph View

Visualize policy relationships:

1. Click Graph View in the policies page.
2. See connections between:
   • Derived Roles and Resource Policies
   • Resource Policies and Principal Policies
3. Click nodes to view policy details.

---

Configuration

Policy Fields

Field	Description	Required
Resource	Resource type	Yes (Resource Policy)
Principal	User identifier	Yes (Principal Policy)
Version	Policy version	Yes
Rules	Access rules	Yes

Rule Fields

Field	Description
Actions	List of actions (read, write, etc.)
Effect	EFFECT_ALLOW or EFFECT_DENY
Roles	Roles this rule applies to
Condition	CEL expression for conditional access

---

Condition Expressions (CEL)

Common expressions for conditions:

# Check attribute equality
request.resource.attr.owner_id == request.principal.id

# Check if attribute exists
has(request.resource.attr.is_published)

# Check list membership
request.principal.attr.department in ["engineering", "product"]

# Date comparison
timestamp(request.resource.attr.created_at) > now() - duration("24h")

---

Limits

Resource	Limit
Policies per app	100
Rules per policy	50
Test scenarios per policy	20

info

Need higher limits? Contact support to discuss your requirements.

---

Troubleshooting

Access unexpectedly denied

Problem: A user should have access but is being denied.

Solution:

1. Use the Test tab to simulate the access check.
2. Verify the user has the required role.
3. Check condition expressions for errors.
4. Look for EFFECT_DENY rules that may be blocking.

---

Policy not being applied

Problem: Policy changes aren't affecting access checks.

Solution:

1. Verify the policy is saved (check for unsaved changes).
2. Ensure the resource type matches exactly.
3. Check the policy version is "default" or matches your config.

---

Condition syntax error

Problem: CEL condition expressions are invalid.

Solution:

1. Check the CEL expression syntax.
2. Verify attribute names match your data model.
3. Use the code editor's syntax highlighting for hints.

---

Related

• Roles
• Apps
• Functions

Last Updated: January 2025